Repository navigation
feat(Conformance): split the self link rules into MUST and SHOULD (#309) - #384
Merged
Merged
Conversation
…309) Follow-up to #376, per the owner decisions on #309 (2026-10-15). - `spec/links/relationship-self-dereferences` (MUST) now holds a relationship's `self` to answering resource linkage of the right shape: `null`, a resource identifier object or an array of them, identifier objects only (`type`, `id`/`lid`, `meta`), so full resource objects fail, with the cardinality the relationship's linkage shows. - New `spec/links/relationship-self-matches-linkage` (SHOULD) compares the answer's identifiers with the relationship's linkage: equality, a subset when either side carries `next`, not decided when both do. - `spec/links/top-level-self-dereferences` (MUST) holds a top-level `self` to answering resource data. - New `spec/links/top-level-self-matches-document` (SHOULD) holds it to a document of the same kind, the collection comparison unchanged. - Each SHOULD leaves what its MUST fails not decided, naming it, as `related-matches-linkage` does since #312. - Review nits: restore "the related resource data" in the non-2xx `expected`; name the endpoints the top-level rules search in their skip reason; pin the four outcomes in each example's conformance test; mention `relationships/comments` in the github example's module doc. Docs (`docs/conformance.md` §1.5, §3, §8, §9, §10) and the unreleased changeset updated. Refs #309 Claude-Session: https://claude.ai/code/session_0187g2QpzaHqEzX8GJxiJBVc Co-Authored-By: Claude <noreply@anthropic.com>
This was referenced Oct 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Refs #309. This is a follow-up to #376. It applies the owner decisions on #309 (issuecomment-6190325231, 2026-10-15) and the #376 review nits.
Both
selflink rules now split into a MUST and a SHOULD, following the #312 precedent (related-dereferences/related-matches-linkage). Each SHOULD leaves a link that its MUST fails as not decided, and names the MUST: a link that does not parse, answers a non-2xx, or answers something the MUST rejects. So a single broken link is never failed twice.spec/links/relationship-self-dereferencesnull, a resource identifier object, or an array of them. Identifier objects only: a stringtype, a stringidorlid, and nothing else butmeta. Full resource objects (attributes/relationships/links) fail; previouslyisResourceObjectonly checked for a stringtype. The cardinality must also match the relationship's linkage:nullor one identifier for to-one, an array for to-many.spec/links/relationship-self-matches-linkage(new)next, and not decided when both do.spec/links/top-level-self-dereferencesspec/links/top-level-self-matches-document(new)nullfornull, or a collection for a collection. The collection comparison is unchanged: an unordered set, compared only when neither document pages.skip: ["spec/links/"]drops all seven link rules, and a test pins this. The example relationship endpoints stay.Review nits
links.ts(non-2xxexpected): "the related resource data" is restored and pinned by a test.ANSWERSgains anamedfield so that the wording for each basis is explicit.noProbeReason) now names "JSON:API read endpoint answering a document" instead of "endpoint answering resource objects". A test pins it.selfrules: both MUSTs Passed,top-level-self-matches-documentPassed, andrelationship-self-matches-linkageSkipped, because the only relationships with aselflink are the links-only paginated ones.examples/github/api.tsmodule doc: mentionsrelationships/comments.Docs and changeset
docs/conformance.md: rule count is 57 (51spec, 6profile) with six gaps. The old status line said 52 and seven, which was already stale before this PR.selfquestion is marked answered.selflinks #376 already removed the gap row, and nothing else in §5 concerns these links.skipexample, which is still correct..changeset/conformance-self-link-rules.mdis not in tag@thomasfosterau/effect-jsonapi@0.16.3, so it is unreleased. It is edited in place and staysminor.Tests and mutation checks. Each mutation was applied to
links.tsand the link suite was run. Every one was killed:The github example's pin was checked the same way: a
paginatedRelationshipselfpointed at/issues/:id/relationships/nowherefails both the pin andKNOWN_FAILURES.Verification
pnpm install --frozen-lockfile: passvp run build: passvp check: pass (0 errors; 4351 warnings, the same as trunk; no new warning sites in the changed files)vp run check(sources, type-level tests, examples, emitted declarations): passvp run -r test:unit: pass (root 3519 tests, examples 44 / 46 / 56)vp run docgen(every JSDoc@examplecompiled and executed): passfallow audit --format json --quiet --explain --gate-marker agent: verdictpassfallow audit --base origin/trunk: "No issues in 9 changed files". 7 inherited findings are excluded.Changeset
.changeset/for every change to published behaviour:.changeset/conformance-self-link-rules.md(minor) is rewritten in place. It is unreleased: it is not in@thomasfosterau/effect-jsonapi@0.16.3.Notes
nullor an object means to-one, an array means to-many. A links-only relationship, such as everyHandlers.paginatedRelationship, shows no cardinality, so it is held only to answering linkage of either kind. The kit does not read the declaredRelationshipfrom theHttpApi:Discoveredcarries no relationship schema. Deriving it from the api would also hold links-only relationships to their declared cardinality. That is possible later, if wanted.lidpasses the MUST. The SHOULD compares bytype/id, so it cannot compare that identifier and leaves the link not decided, as it does for any answer it cannot identify.Handlers.paginatedRelationshipalways writes a relationshipselflink) is untouched.🤖 Generated with Claude Code
Generated by Claude Code